home *** CD-ROM | disk | FTP | other *** search
/ BBS Toolkit / BBS Toolkit.iso / wildcat / wcolor.zip / WCOLOR.DOC < prev    next >
Text File  |  1992-06-02  |  15KB  |  356 lines
  1.             ════════════════════════════════════════
  2.  
  3.                           W C O L O R
  4.  
  5.             ════════════════════════════════════════
  6.                           Version 1.0
  7.  
  8.                      By:  Zenon O. Ruzycky
  9.  
  10.  
  11. Summary
  12. ───────
  13.  
  14. This program is designed to convert between `ansi' files and
  15. WILDCAT! BBS `@' coded files (and visa versa), while optimizing
  16. the output in the process.  Files created for WILDCAT! version
  17. 3.5 are also supported.
  18.  
  19. The display option allows file previewing at speeds simulating
  20. baud rate, which allows the designer to preview the file at the
  21. speed viewed by the user.  And in the case of animated `ansi'
  22. files this option is handy to `slow down' the action.
  23.  
  24. B&W image viewing is also possible when displaying files.  This
  25. is performed by simply pressing the `SPACE' bar.  This feature
  26. gives you an easy way to preview the file as the non-color user
  27. would see it.
  28.  
  29. By converting BBS `@' codes to `ansi' codes, any popular `ansi'
  30. drawing routines may be used to edit the image.  Re-conversion
  31. back to BBS `@' code format is then easily acheived with the same
  32. program.
  33.  
  34. Handy batch files are also included to simplify operation.  These
  35. may be used as is, or modified as needed.
  36.  
  37.  
  38. Registration
  39. ────────────
  40.  
  41. WCOLOR is distributed as shareware.  It may only be duplicated
  42. for personal or non-commercial use, and may not be modified or
  43. customized in any way shape or form without the consent of the
  44. author.  In addition, the authors written consent is needed prior
  45. to being sold, distributed or marketed with any other product or
  46. service.
  47.  
  48. If you find WCOLOR fast, easy, and convenient to use, a $15
  49. registration fee is appreciated.  Please send check or money
  50. order to:
  51.  
  52.                         Zenon O. Ruzycky
  53.                         92 Laurelwood Dr.,
  54.                         Hopedale, MA, 01747
  55. Command Line Options
  56. ────────────────────
  57.  
  58. To simplify its use, the supplied program `WCOLOR.EXE' and the 7
  59. batch files should be placed in a directory which is included in
  60. the `DOS path'.  The following is the format for the command line
  61. (case is ignored):
  62.  
  63.  
  64. ╓────────────────────────────────────────────────────────────╖
  65. ║  WCOLOR -I{A/B}{filename} [-O{A/B}{filename}] [-D[xxxxx]]  ║
  66. ╙────────────────────────────────────────────────────────────╜
  67.  
  68.       Square brackets `[]' denote optional parameters, and
  69.       curly brackets `{}' denote required parameters.
  70.  
  71.  
  72. -I:   Input file - followed by file `type' and `filename'.
  73.  
  74.             The file type is either `A' or `B' representing `ansi'
  75.             codes, or BBS `@' codes.  Either `A' or `B' must be
  76.             entered, but not both.  If both are entered, the second
  77.             will be mistaken for part of the file name - an error
  78.             opening the input file may result.
  79.  
  80.             The `filename' must be an existing file of `type', and
  81.             may include the drive and full path designation.
  82.  
  83. -O:   Output file - followed by file `type' and `filename'.
  84.  
  85.             See `-I' for explanation of `type' and `filename'.
  86.  
  87. -D:   Display option.
  88.  
  89.             If present, this parameter determines if the input
  90.             file is displayed.  The display speed may also be
  91.             optionally set by entering a number `xxxxx' after
  92.             `-D'.
  93.  
  94.             The number `xxxxx' crudely represents the display
  95.             speed in baud, and may be any positive number
  96.             (including `0').  However, if omitted or = 0,
  97.             display speed is the fastest.
  98.  
  99.             Since delay times are calculated in milliseconds, any
  100.             number greater than 9,000 will acheive the same result
  101.             as entering `0'.
  102.  
  103.             If the output file is omitted, display is assumed. 
  104.             And will ocurr at speed `0' unless otherwise
  105.             specified.
  106.  
  107.  
  108. Examples:   WCOLOR -IAtest.ans -D2400
  109.             - view ansi file `test.ans' at ~2400 baud.
  110.  
  111.             WCOLOR -IBtest.bbs -OAtest.ans
  112.             - converts BBS file `test.bbs' to ansi file `test.ans'
  113.             without display.
  114. Operation
  115. ─────────
  116.  
  117. To begin using this utility, you should place the file
  118. `WCOLOR.EXE' and it's batch files in a directory located in the
  119. `DOS path'.  Then change directories (and/or drives) to the
  120. location where file conversion and display is to be performed. 
  121. The rest is performed by either issuing command line options for
  122. `WCOLOR', or by the using the batch files.
  123.  
  124. If an output file is specified with no display, uninterrupted
  125. file conversion will result.
  126.  
  127. If display is specified in any mode, pressing any key will pause
  128. file display until another key is pressed.  This is handy to
  129. `freeze action' during animated file display, or even if viewing
  130. text files.  Once display is completed, available options are
  131. displayed on the help line at the bottom of the screen, or by
  132. pressing <F1> (if output file specified).
  133.  
  134. Available options are as follows:
  135.  
  136. a)    Pressing the space bar will toggle the display between color
  137.       and B&W.  This will permit you to view the file as if color
  138.       had been turned OFF in the BBS.  Displaying in B&W will
  139.       still save images with color codes.
  140.  
  141. If an output file is specified, the following functions are also
  142. available:
  143.  
  144. b)    Pressing `ESC' will abort the conversion.
  145.  
  146. c)    The cursor positioning keys can be used to select a new
  147.       position for the final cursor location (see `Final Cursor
  148.       Resting Position' below).
  149.  
  150. d)    The image may be `flipped' left<-->right by pressing the
  151.       `tab' key, and top<-->bottom by pressing `shift tab'.  This
  152.       procedure WILL affect the converted image.  Text and graphic
  153.       characters that have mirror images are flipped (such as `<'
  154.       to `>', and `╙' to `╓' and so on ...).
  155.  
  156. e)    Image scrolling left<-->right and top<-->bottom is
  157.       accomplished by using the `Ctrl' key in comination with the
  158.       left/right arrow keys and the PgUp/PgDn keys.
  159.  
  160. When specifying input/output files, any discrete file naming
  161. convention may be used.  This includes pre-specifying drive and
  162. sub-directory information with the file name.  For example, in
  163. the current directory the input file name `IN_FILE.BBS' may be
  164. given, but the output file may be re-directed to an alternate
  165. directory such as `C:\WILDCAT\DISP\OUT_FILE.BBS'.  DOS short hand
  166. notation may also be used, such as:  `.' and `..' - to specify
  167. current and parent directories.
  168.  
  169. If the bell character is present in the display file, it will be
  170. preserved only if it occurred immidiately before the screen was
  171. cleared, or any time after that.  Bell characters are remembered
  172. by screen position, and are virtually unlimited in quantity.
  173. Final Cursor Resting Position
  174. ─────────────────────────────
  175.  
  176. If an output file is specified (file conversion assumed), a
  177. flashing `■' will mark the final cursor position after
  178. optimization.
  179.  
  180. This is also the position where further system prompts will be
  181. displayed.
  182.  
  183.  
  184. Limitations
  185. ───────────
  186.  
  187. The program will convert any `ansi' or BBS `@' coded file
  188. designed to fit within 80 columns and 25 lines.  However, only
  189. one file may be specified at a time.  This precludes the use of
  190. the DOS wildcard characters `?' and `*'.
  191.  
  192. When converting to BBS `@' codes, the output file is trimmed to
  193. 79 columns.  Since BBS `@' codes don't have cursor positioning
  194. capability, there is no way to place a `CR/LF' after the 80th
  195. column of solid character display without loosing 1 full row. 
  196. This can be overcome by stringing characters together without a
  197. `CR/LF' thereby resulting in line wrap.  However, after several
  198. lines DOS may intervene and insert a `CR/LF' without regard for
  199. asthetics.  This may also occur within an escape sequence thereby
  200. damaging the escape command structure, leading to undesired color
  201. or screen cursor positioning.  By trimming the 80th column, this
  202. effect can be eliminated.  However, display screens will need to
  203. be designed with this point in mind.
  204.  
  205. Files longer than 25 lines may be displayed, however, if an
  206. output file is specified only the final screen will be converted,
  207. and any text/graphics scrolled off the screen will be lost.  The
  208. same principle holds true when converting animated ansi files -
  209. meaning, only the final display is converted.
  210.  
  211. The following ansi codes are not supported by this program:
  212.  
  213.             ESC[=xh     Set mode (screen size)
  214.             ESC[=xl     Reset mode
  215.             ESC...p     Key re-definition
  216.  
  217. BBS `@' codes affecting color, screen pausing and clearing as
  218. well as bells are enterpreted, while all other `@' codes are
  219. displayed.  The exception to this is the `@PAUSE@' command which
  220. is displayed AND enterpretted.
  221. Note:       When converting WILDCAT! version 3.5 (and higher)
  222.             files, keep in mind that only the final display is
  223.             converted.  Therefor, any file making use of the
  224.             following constructs will not be properly converted:
  225.  
  226.                         @IFSEC=PROFILE@
  227.                               display_code
  228.                         @ELSE@
  229.                               display_code
  230.                         @ENDIF@
  231.  
  232.             If these constructs are to be used, their individual
  233.             `display_code' should be generated separately, then re-
  234.             compined into a master file using a text editor.
  235.  
  236.  
  237. Batch Files
  238. ───────────
  239.  
  240. Although `WCOLOR.EXE' will perform all file viewing and
  241. conversion on its own, its operation can be enhanced by the use
  242. of batch files.
  243.  
  244. There are 7 batch files included with this package, which
  245. simplify operation.  All are desinged to scan input variables to
  246. determine if minimum input is present, and all are designed to
  247. display the input file on the screen.  The default speed is `0'
  248. unless otherwise specified.
  249.  
  250. The command line options of each batch file are as follows:
  251.  
  252.       i)    wa   ansi_file                  [speed]
  253.       ii)   wb    bbs_file                  [speed]
  254.       iii)  waa  ansi_in_file ansi_out_file [speed]
  255.       iv)   wab  ansi_in_file  bbs_out_file [speed]
  256.       v)    wba   bbs_in_file ansi_out_file [speed]
  257.       vi)   wbb   bbs_in_file  bbs_out_file [speed]
  258.       vii)  wbab  bbs_file                  [speed]
  259.  
  260. Batch files i) and ii) are intended to view an `ansi' or `BBS'
  261. file only.
  262.  
  263. Files iii) to vi) perform a conversion between the input and
  264. output files.  The batch file name indicates the type of
  265. conversion, eg.  `wab.bat' converts an `ansi' file to a `BBS'
  266. file.  The `waa.bat' and `wbb.bat' files simply optimize the
  267. input file.
  268.  
  269. Batch file vii) first makes a backup copy of `bbs_file' to
  270. `\wcolor.bak', then converts it from `BBS' to `ansi' format
  271. (without display).  It's then loaded into an `ansi' editor for
  272. editing (shown as `THEDRAW' in this example).  When exiting the
  273. `ansi' editor, the file is re-converted into `BBS' format (with
  274. display).  However, if final conversion is aborted by pressing
  275. <ESCAPE>, the file `\wcolor.bak' is copied back to the original
  276. file.  In either case, the file `\wcolor.bak' is deleted.
  277.  
  278. For all batch files requiring an output file name, the
  279. expressions `*.*' or `.' may be used in place of the output file
  280. name.  This will force the input file name to be substituted for
  281. the output file name.  However, since these designations are
  282. strictly defined in the batch files, they may be changed to any
  283. designation desired.
  284.  
  285. Presently all batch files display the input file.  However, to
  286. further customize the process, the batch files may be modified to
  287. check for the presence of the `speed' variable, and if not
  288. present display may be omitted.
  289.  
  290. The following code is an example of how the `wab.bat' file could
  291. be modified to bypass display if the `speed' variable is omitted
  292. (added lines are tagged with an `*'):
  293.                
  294.       ┌────────────────────────────────────────────────────────┐
  295.       │    @echo off                                           │
  296.       │    if "%1" == ""    goto ERROR                         │
  297.       │    if "%2" == ""    goto ERROR                         │
  298.       │    if "%2" == "*.*" goto REPEAT                        │
  299.       │    if "%2" == "."   goto REPEAT                        │
  300.       │                                                        │
  301.       │  * if "%3" == "" goto NO_DISP1                         │
  302.       │    wcolor -ia%1 -ob%2 -d%3                             │
  303.       │    goto CHECK                                          │
  304.       │                                                        │
  305.       │  * :NO_DISP1                                           │
  306.       │  * wcolor -ia%1 -ob%2                                  │
  307.       │  * goto CHECK                                          │
  308.       │                                                        │
  309.       │    :REPEAT                                             │
  310.       │  * if "%3" == "" goto NO_DISP2                         │
  311.       │    wcolor -ia%1 -ob%1 -d%3                             │
  312.       │  * goto CHECK                                          │
  313.       │                                                        │
  314.       │  * :NO_DISP2                                           │
  315.       │  * wcolor -ia%1 -ob%1                                  │
  316.       │                                                        │
  317.       │    :CHECK                                              │
  318.       │    if errorlevel 0 goto EXIT                           │
  319.       │                                                        │
  320.       │    :ERROR                                              │
  321.       │    echo Batch format is `wab ansi_in bbs_out [speed]'  │
  322.       │                                                        │
  323.       │    :EXIT                                               │
  324.       └────────────────────────────────────────────────────────┘
  325.  
  326. These batch files are intended as a starting point, and may be
  327. altered to provide operation best suited to your needs.  Also,
  328. when using these files, keep in mind that they assume external
  329. programs (including `WCOLOR.EXE') are defined in the DOS path.
  330. Errorlevels
  331. ───────────
  332.  
  333. A diferent DOS errorlevel is issued on every exit condition of
  334. `WCOLOR.EXE'.  These are intended to give you the most
  335. flexibility when processing your conversions through batch
  336. commands.
  337.  
  338. A list of exit conditions is listed below:
  339.  
  340.       Errorlevel 1:     No command line parameters.
  341.       Errorlevel 2:     Input  file could not be opened.
  342.       Errorlevel 3:     Output file could not be opened.
  343.       Errorlevel 4:     Not Used.
  344.       Errorlevel 5:     General `Syntax Error'.
  345.       Errorlevel 6:     Parameters must begin with `-'.
  346.       Errorlevel 7:     Invalid parameters given.
  347.       Errorlevel 8:     Input file parameter syntax error.
  348.       Errorlevel 9:     Input file type must be `A' or `B'.
  349.       Errorlevel 10:    Output file parameter syntax error.
  350.       Errorlevel 11:    No input file specified.
  351.       Errorlevel 12:    Output file type must be `A' or `B'.
  352.       Errorlevel 13:    Not Used.
  353.       Errorlevel 14:    Not Used.
  354.       Errorlevel 50:    Undefined error.
  355.       Errorlevel 100:   <ESCAPE> key pressed.
  356.